BMediaFiles

Derived from: none

Library: libmedia.so

Allocation: Constructor only

Summary

One feature provided by the Media Kit is the ability to assign media files (sounds and graphics files, for example) to named elements, which can then be used to locate user-configured sound and graphics options.

That's the technical way of saying that the Media Kit provides the ability to assign sounds and bitmap graphics to events and system attributes, so you can configure the appearance and behavior of your BeOS computer's user interface.

Identifying an Entry

Each entry in the media files registry consists of three elements: a type, an item name, and an entry_ref. The type is the type of media data the entry represents. For example, this could be "sound" or "bitmap." The item name is the actual name of the entry in the registry, such as "Startup" or "desktop image." The entry_ref identifies the file that's been assigned to that particular entry.

An application can instantiate a BMediaFiles object and then use the GetRefFor() function to find out what file is assigned to a particular registry entry. For instance, if your application needs to access the desktop image file, you can get this information as follows:

      entry_ref ref;
   
      if (GetRefFor("bitmap", "desktop image", &ref) == B_OK) {
         /* have your way with the desktop image file */
      }

The user uses the Sounds preference application to assign sound files to events, such as the system beep and the startup sound. These are named "Beep" and "Startup" respectively. The beep() function will always play whatever sound is assigned to the Beep event.

Hook Functions

GetNextRef()

GetNextType()

GetRefFor()

RemoveRefFor()

RewindRefs()

RewindTypes()

SetRefFor()

Constructor and Destructor

BMediaFiles()

BMediaFiles(void)

Constructor.

~BMediaFiles()

virtual ~BMediaFiles(void)

Destructor.

Member Functions

GetNextRef()

virtual status_t GetNextRef(BString *outType,
      entry_ref *outRef = NULL)

Returns the next media type in outType. These types include things like "sound" and "bitmap."

RETURN CODES

B_OK. No error.

B_BAD_INDEX. No more entry_refs to get.
B_BAD_VALUE. outType is NULL.

GetNextType()

virtual status_t GetNextType(BString *outType)

Returns the next media type in outType. These types include things like "sound" and "bitmap."

RETURN CODES

B_OK. No error.

B_BAD_INDEX. No more types to get.

GetRefFor() , SetRefFor() , RemoveRefFor()

virtual status_t GetRefFor(const char *type,
      const char *item,
      entry_ref *outRef )

virtual status_t SetRefFor(const char *type,
      const char *item,
      entry_ref &outRef )

virtual status_t RemoveRefFor(const char *type,
      const char *item,
      entry_ref &outRef )

GetRefFor() returns the entry_ref for the media file that's been assigned to the specified type and item name pair. For example, if you wanted to retrieve the sound file that's been assigned as the system startup sound, you might specify type as "sound" and item as "startup sound."

SetRefFor() sets, by entry_ref, the file to be used for the specified type/item pairing.

RemoveRefFor() removes the specified entry_ref for the given type/item pairing.

RETURN CODES

B_OK. No error.

B_ENTRY_NOT_FOUND. (GetRefFor() only) the specified type/item pair isn't assigned.

RemoveRefFor() see GetRefFor()

RewindRefs()

virtual status_t RewindRefs(const char *type)

Rewinds the entry_ref list for the specified media type, so you can start scanning from the beginning of the list.

RETURN CODES

B_OK. No error.

B_BAD_VALUE. type is NULL.
Other errors. Unable to rewind; the Media Server may not be responding.

RemoveItem()

virtual status_t RemoveItem(const char *type)

Removes an entrire entry from the media files database. Unlike RemoveRefFor(), which removes an entry_ref from an entry, this function actually deletes the entire entry.

RETURN CODES

B_OK. No error.

Other errors. Unable to remove the item; the Media Server may not be responding.

RewindTypes()

virtual status_t RewindTypes(void)

Rewinds to the beginning of the media type list. If you've been using a BMediaFiles object and want to begin scanning again from the beginning of the media type list, you should call this function.

RETURN CODES

B_OK. No error.

Other errors. Unable to rewind; the Media Server may not be responding.

SetRefFor() see GetRefFor()

The Media Kit Table of Contents

The Media Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.